/*
 * AscTextDataItem.java
 *
 * Created on August 27, 2002, 1:19 PM
 *
 * Copyright (c) 2002 The General Electric Company
 */

package com.ge.healthcare.autosc.common.util.dataItem;

import java.io.File;
import java.io.PrintWriter;

import com.ge.healthcare.autosc.common.exceptions.BasicException;

/**
 * Interface for accessing and updating a textual data item.  Textual
 *  data items are used to identify data in a manner analogous to
 *  java.io.File objects.
 *
 * @author Daniel S. Horwitz, Compuware Corp.
 *
 * @version AutoSC P5P6
 */
public interface IASCTextDataItem
{
    /**
     * Does the data identified by this data item exist?
     *
     * @return True if the data exists, false if not.
     */
    boolean exists();

    /**
     * Get File object for this data item
     * @return
     */
    public File getDataSourceFile();

    /**
     * Delete the data identified by this data item.  Being unable to
     *  delete the data is considered an error, but not a fatal error.
     *  If the data does not exist, then the deletion is assumed to
     *  have succeeded.
     *
     * @return True if the data was deleted, false if not.
     */
    boolean delete();

    /**
     * Open, for reading, the data identified by this data item.  It is
     *  the responsibility of the calling code to close the reader.
     *
     * @return Reader to use for reading the data.
     *
     * @exception AscServiceAbortException If unable to open the data.
     */
    IASCTextReader openForReading() throws BasicException;

    /**
     * Open, for writing, the data identified by this data item.  The
     *  existing data will be overwritten.  It is the responsibility
     *  of the calling code to close the writer.
     *
     * @return Writer to use for writing the data.
     *
     * @exception AscServiceAbortException If unable to open the data.
     */
    PrintWriter openForWriting() throws BasicException;

    /**
     * Open, for writing, the data identified by this data item.  It is
     *  the responsibility of the calling code to close the writer.
     *
     * @param append True if appending to the data, false if the data should be
     *   overwritten.
     *
     * @return Writer to use for writing the data.
     *
     * @exception AscServiceAbortException If unable to open the data.
     */
    PrintWriter openForWriting( boolean append )
        throws BasicException;

    /**
     * Move the data to a different data item.  This moves the data from
     *  this data item to the destination data item.  If the destination
     *  data item contains existing data, the existing data is first
     *  deleted.  Once the move is complete, this data item will no longer
     *  contain any data.
     *
     * @param destination The data item to which this data item's data will
     *  be moved.
     *
     * @exception AscServiceAbortException If unable to move the data.
     */
    void move( IASCTextDataItem destination )
        throws BasicException;

    /**
     * Copy data from this data item to the destination data item.
     * @param destination The data item to which this data item's data will
     *  be copied.
     * @throws BasicException
     */
    public void copy( IASCTextDataItem destination )
    	throws BasicException;
    
    /**
     * Sort this data item's data, removing duplicates, and place the
     *  resulting data in the destination data item.  Any existing data
     *  in the destination data item is overwritten.  This data item's
     *  data remains unchanged.
     *
     * @param destination The data item where the results of the sort will
     *  be stored.
     *
     * @exception AscServiceAbortException If unable to sort the data or
     *  write it to the destination data item.
     */
    void sortAndRemoveDuplicates( IASCTextDataItem destination )
        throws BasicException;
}
